---
title: "Image"
description: "The Image component is used to display images with support for fallback."
---

import {imageContent} from "@/content/components/image";

# Image

The Image component is used to display images with support for fallback.

<ComponentLinks component="image" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add image",
    npm: "npm install @heroui/image",
    yarn: "yarn add @heroui/image",
    pnpm: "pnpm add @heroui/image",
    bun: "bun add @heroui/image"
  }}
/>


## Import

<ImportTabs
  commands={{
    main: 'import {Image} from "@heroui/react";',
    individual: 'import {Image} from "@heroui/image";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={imageContent.usage} />

### Blurred

You can use the `isBlurred` prop to duplicate the image and blur it to create a blurred effect.

<CodeDemo title="Blurred" files={imageContent.blurred} />

### Zoomed

You can use the `isZoomed` prop make the image zoomed when hovered.

<CodeDemo title="Zoomed" files={imageContent.zoomed} />

### Animated Loading

Image component has a built-in `skeleton` animation to indicate the image is loading and an
`opacity` animation when the image loads.

<CodeDemo displayMode="visible" title="Animated Loading" files={imageContent.loading} />

> **Note**: The `URL` uses `https://app.requestly.io/delay` to simulate a slow network.

### Image with fallback

You can use the `fallbackSrc` prop to display a fallback image when:

- The `fallbackSrc` prop is provided.
- The image provided in `src` is still loading.
- The image provided in `src` fails to load.
- The image provided in `src` is not found.

<CodeDemo displayMode="visible" title="Image with fallback" files={imageContent.fallback} />

### With Next.js Image

Next.js provides an optimized [Image](https://nextjs.org/docs/app/api-reference/components/image) component,
you can use it with HeroUI `Image` component as well.

<CodeDemo showPreview={false} showOpenInCodeSandbox={false} title="With Next.js Image" files={imageContent.nextjs} />

> **Note**: HeroUI's `Image` component is `client-side`, using hooks like `useState` for loading states
> and animations. Use Next.js `Image` alone if these features aren't required.

## Slots

- **img**: Slot for the image element.
- **wrapper**: Image wrapper, it handles alignment, placement, and general appearance.
- **zoomedWrapper**: The wrapper slot for the zoomed image it avoids the image content to overflow the parent container.
- **blurredImg**: The wrapper slot for the duplicated blurred image.

<Spacer y={4} />

## API

### Image Props

<APITable
  data={[
    {
      attribute: "src",
      type: "string",
      description: "The image source.",
      default: "-"
    },
    {
      attribute: "srcSet",
      type: "string",
      description: "The image srcSet.",
      default: "-"
    },
    {
      attribute: "sizes",
      type: "string",
      description: "The image sizes.",
      default: "-"
    },
    {
      attribute: "alt",
      type: "string",
      description: "The image alt.",
      default: "-"
    },
    {
      attribute: "width",
      type: "number",
      description: "The image width.",
      default: "-"
    },
    {
      attribute: "height",
      type: "number",
      description: "The image height.",
      default: "-"
    },
    {
      attribute: "radius",
      type: "none | sm | md | lg | full",
      description: "The image border radius.",
      default: "lg"
    },
    {
      attribute: "shadow",
      type: "none | sm | md | lg",
      description: "The image shadow.",
      default: "none"
    },
    {
      attribute: "loading",
      type: "eager | lazy",
      description: "A loading strategy to use for the image.",
      default: "-"
    },
    {
      attribute: "fallbackSrc",
      type: "string",
      description: "The fallback image source.",
      default: "-"
    },
    {
      attribute: "isBlurred",
      type: "boolean",
      description: "Whether the image should have a duplicated blurred image at the background.",
      default: "false"
    },
    {
      attribute: "isZoomed",
      type: "boolean",
      description: "Whether the image should be zoomed when hovered.",
      default: "false"
    },
    {
      attribute: "removeWrapper",
      type: "boolean",
      description: "Whether to remove the wrapper element. This will cause the image to be rendered as a direct child of the parent element. If you set this prop as `true` neither the skeleton nor the zoom effect will work.",
      default: "false"
    },
    {
      attribute: "disableSkeleton",
      type: "boolean",
      description: "Whether the image should disable the skeleton animation while loading.",
      default: "false"
    },
    {
      attribute: "classNames",
      type: 'Partial<Record<"img" | "wrapper" | "zoomedWrapper" | "blurredImg", string>>',
      description: "Allows to set custom class names for the image slots.",
      default: "-"
    }
  ]}
/>

### Image Events

<APITable
  data={[
    {
      attribute: "onLoad",
      type: "ReactEventHandler<HTMLImageElement>",
      description: "Handler that is called when the image load.",
      default: "-"
    },
    {
      attribute: "onError",
      type: "() => void",
      description: "Handler that is called when the image fails to load.",
      default: "-"
    }
  ]}
/>
